home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 August / Macworld (1997-08).dmg / Serious Demos / Crimson Demo / Crimson Basic Manual / Crimson Basic Manual.rsrc / TEXT_1800_TDL.txt < prev    next >
Text File  |  1997-06-17  |  3KB  |  76 lines
  1.     
  2. TDL and the Toolbox
  3.  
  4. Overview    
  5. The TDL (Toolbox Definition Language) compiler enables new Toolbox traps to be added to the Development System.
  6. In most cases it will not be necessary to call the Macintosh Toolbox interface to achieve your goals within Crimson Basic, as most high level functions are performed automatically by the language.
  7.  
  8. What are Toolbox Calls ?    
  9. Toolbox Calls are a low level interface to Operating System functions within the Macintosh Operating System.
  10. Traditionally, when using a language such as 'C', the only way to build GUI interfaces was to use the Toolbox interface directly, which is tedious and error prone.
  11. Having said this, advanced programmers may wish to use this interface to access low level functions which are not available within Crimson Basic. Hence the TDL Compiler is included for completeness.
  12.  
  13. Understanding TDL    
  14. Toolbox Traps are defined in the 'ToolBoxTraps' file within the TDL folder. A Toolbox call definition is expressed as a number of parameters :
  15.  
  16. Name
  17. The name of the ToolBox call.
  18.  
  19. Trap
  20. The hexadecimal representation of the 'A' Trap by which the Operating System understands the Trap.
  21.  
  22. Type
  23. Toolbox Traps fall into two categories :
  24.     Register based (R), where the parameters are passed in processor registers.
  25.     Stack based (S), where the parameters are passed on the stack.
  26.  
  27. Inparm
  28. Describes the input parameters to the Toolbox call in terms of Basic data types. These are:
  29.  
  30. For Type='S' (Stack Based)
  31.   I    - Integer (any 32 bit value, including Pointers and Handles).
  32.   W   - Word (any 16 bit value)
  33.   B    - Byte (any 8 bit value)
  34.   P    - Pascal String (data type Str255)
  35.   T    - Data in a Structure
  36.   C    - A fixed length character string (data type Char)
  37.  
  38. For Type='R' (Register based)
  39.   A0  - the A0 register
  40.   D0  - the D0 register
  41.  
  42. Outparm
  43. Describes the output parameters from the Toolbox call.
  44. The data types are the same as for Inparm.
  45.  
  46. SelType (optional)
  47. Some Toolbox calls have the same Trap number and use a Selector to distinguish between them :  
  48.   R  - Register based
  49.   S  - Stack based
  50.  
  51. Selector (optional)
  52. The numeric Selector required to complete the ToolBox call definition.
  53.  
  54. Sources of Information    
  55. Anyone interested in studying the Toolbox calls available within the Macintosh Operating System (not for the faint hearted) should refer to the 'Inside Macintosh' documentation (downloadable for free) at the Apple Web site:
  56. http://devworld.apple.com/dev/insidemac.shtml
  57. The volumes of most interest are :
  58.     Toolbox Essentials,
  59.     More Macintosh Toolbox,
  60.     Memory.
  61.  
  62. Using TDL    
  63.  The ToolBoxTraps file provided contains most of the commonly used Toolbox Traps and these are already available for use within Crimson Basic.
  64. A Toolbox trap is coded like any other call to a Procedure or Function except that the Name of the Trap is preceded by a "_" character. For example.
  65.  
  66. To allocate a handle to an area of memory :
  67.     Global Handle As Integer
  68.     Handle=_NewHandle(666)  ..  will allocate a handle to a new area of memory of
  69.                                                666 bytes.
  70.  
  71.     Global WinPtr As Integer
  72.     Global WinTitle As Str255[255]
  73.         _SetWTitle(WinPtr,WinTitle)  ..  will change a Windows Title
  74.  
  75. Don't be put off by the complexity of TDL, its well worth the effort to study this low level interface if you're interested in getting into the 'bowels' of the Mac Operating System.
  76.